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1. BASIC COMMANDS 



This chapter will provide what you need to know to create a document with 
^TgX. Generally speaking, the commands described below can be divided into two 
groups: those that control the "global" parameters of the document (like the base 
type size, page dimensions, etc.), and those that affect the "local" appearance of the 
text (size or style changing, centering, etc.). There are some restrictions on the use 
of the global commands. First, they generally should be invoked only once (if at all), 
at the beginning of your file. (This is not a hard-and-fast rule; most can be used 
more than once, but it should be rarely necessary and is not recommended unless 
you have a good understanding of what they do.) Second, the order in which these 
commands appear is mildly important, so read carefully. You can also consult the 
T^ file that produced this document for an example of their use. 

I.l. Using Fonts 

This section describes how to access the veritable plethora of fonts provided by 
3yi^E^. Many examples of the different sizes and styles are given here; the symbol "•" 
will appear in inappropriate places below if any are unavailable on your machine. 
(Normally, warnings about unavailable fonts are written to the terminal as the job is 
run.) 

The \typesize command and size-changing 

The first line of your JyT^ file should contain the \typesize command, which 
establishes what the normal size of fonts in the document will be. (This manual is 
set with \typesize=12pt.) If you're the kind that doesn't fike to be tied down to 
a particular font size, have no fear — a larger font, for example, is only a \bigf onts 
command away. As should be obvious by now, \bigf onts changes the 
normal size fonts, in all styles, into their larger size cousins. 

Actually, there's a little more to it than that. There are two com- 
mands in ^TgX that will produce these large fonts: \bigfonts and 
\bigsize. \bigfonts does exactly what is described above, i.e., re- 
places the normal fonts with larger ones, \bigsize also does this, but 
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in addition scales a number of internal parameters (such as the \base- 
lineskip) so that typesetting with the new size looks more like a scaled 
up version of the normal one. (This paragraph was typeset after first 
giving a \bigsize command. Notice how the line spacing is larger than 

in the previous paragraph.) 

So which command do you use if you want larger fonts? The simple answer is to 
use \bigf onts to enlarge single words or one-line bits of text, and use \bigsize for 
multi-line text or paragraphing. One consideration is that \bigsize is a fairly slow 
and difficult command for ^yT^ to execute compared to \bigf onts, so if typesetting 
speed is an issue it might be worthwhile to eliminate \bigsize commands in favor of 
\bigf onts whereever possible. 

By this time you've probably guessed that \bigf onts and \bigsize aren't the 
only size-changing commands available to you. In fact, there's a whole range of larger 
sizes: 



Command 


Scale factor 


Example 


\bigf onts 


1.2 


Big. 


\Bigf onts 


(1.2)2 


Real big. 


\biggf onts 


(1.2)3 


SUPER big. 


\Biggf onts 


(1.2)^ 


YOW! 



Of course, there are plenty of smaller sizes available also: 
Command Scale factor Example 

Xsmallf onts 1/1.1 "We begin bombing in five minutes." 

\f ootnotef onts 1/1.2 "Wc could do it, but it would be wrong." 

\subscriptf onts 1/(1. 2)^ "I am not a crook." 

\subsubscriptf onts 1/(1.2)^ "Mistakes were made." 

(The names of the last three entries describe their use in JyF^.) Each of these 
has a corresponding \. . .size partner. In addition, there are also the commands 
\tinyfonts and \tinysize (the smallest type available, usually 5pt), \HUGEFONTS 
and \HUGESIZE (the largest type available, usually 25pt), and \normalfonts and 
\normalsize (which return JyT^ to the base size). None of these commands work 
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in math mode (they are ignored). 

As explained above, the \ . . . size version of each command differs from its 
\ . . . fonts counterpart in that it causes internal parameters to be scaled. The most 
important in practice besides the \baselineskip are the sizes of \bigskip, \medskip, 
\smallskip, which are always normalized after a \ . . . size command to correspond 
to a one-line, half- line, and quarter- line skip (with some stretch and shrink), respec- 
tively. 

\typesize is a "global" command and has some limitations. It may only be 
invoked once and, as stated above, should be the first command in your file. Because 
only certain sizes are generally available, the only base sizes supported are lOpt, 
12pt, and 14pt. This means that if you want to typeset a document in, say, llpt, 
you can only get it by \typesize=12pt \smallsize. 

Style-changing commands 

You can also change the type style, rather than the size, in the usual way: for 
example, \it switches to italic type. There's also \rin (roman, the default), \bf 
(bold), \bfs (a slimmer bold than \bf, giving a sort of ninetccnth-ccntury feel), 
\sc (Small Caps), \sl (slanted), \ss (sans serif), and \tt (typewriter). (A size- 
changing command always leaves you with roman type, so if you want large italic 
type you should specify \bigf onts\it, not \it\bigf onts.) In math mode things 
are a bit different: you have the special math styles \init {math italic, the default), 
\bmit (bold math, for bold Fpeen and other symbols), and \cal (for Calligraphic 
characters), as well as the usual \rm, \bf , \bf s, and \it, but you can't say \sc, \sl, 
\ss, or \tt (except inside an \hbox). 

Style-changing commands should be used with caution in math mode. In par- 
ticular, they should be kept confined within braces (the penalty for letting them run 
free could be some unexplainable output). For example, you can't make an equa- 
tion in boldface by typing $$\biiiit. . . $$. The reason for this is that different bold 
symbols come from different fonts, and some symbols have no bold analog at all. 
${\bmit\Phi}$, for example, gives you the bold version of the ^ in the math 
itahc font. But if you want $ (the upright version) you have to say ${\bf \Phi}$, 
because the unbold $ comes from the roman font. The basic rule is this: \bf and 
\bf s give you a bold roman characters and \binit gives you bold math italic. If the 
symbol you want to make bold isn't in either of those fonts you're out of luck. (To 
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see which characters reside in what fonts, see Appendix F of the I^book.) 

You may have noticed that JyT^^s \ss command for invoking the sans serif font 
supercedes the T^jX command that produces "6," the German sharp "s." In ^yT^jX 
you get this character with \ sharps. 

To close this section, you should make sure you understand that a sentence like 
THIS! is produced by 

...a {\subscriptf onts sentence} {\bf like} {\bigf onts\it THIS!} 

1.2. Setting Up a Document 

After giving the \typesize command it's time to specify the general format of 
the document. %T^iX "wakes up" with a format already in place, so you may find that 
you don't need to use many of the commands described below. Generally speaking, 
these are all global commands and should be invoked only once at the beginning of 
the file (except where noted), but if you insist on using them again, at least do it 
after an explicit page break (see \newpage, below). 

Normal vs. two-page output 

The \outputstyle command determines the general layout of the page. There 
arc two styles available: they are selected by the commands \outputstyle{normal} 
and \outputstyle{twoup}. The default is normal. 

When the \outputstyle is normal, the text forms a box on the page whose 
dimensions are the values of the TfrjX registers \vsize and \hsize. The distance of 
this box from the top and left edges of the paper is determined by the -^yl^^X registers 
\topmargin and \lef tmargin. These are initialized by the commands 

\vsize=8.9in \hsize=6.5in 
\topmargin=lin \leftmargin=lin 

Above and below the page arc single lines of text called the headline and footline, 
the contents of which are determined by the token variables \head and \f oot. These 
have the default values 

\head={\hfil} 

\f oot={\hf il\normalf onts\numstyle\pagenum\hf il} 
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As you can see, the \head is normally empty. The definition of \foot requires 
some explanation (see below), but it should be reasonably obvious that it contains a 
centered page number in the base size. 

If you select \outputstyle{twoup}, two pages of the document will appear side 
by side, printed "sideways" on each page of output (you should check that your printer 
has a mode that allows you to print this way). In this case, \vsize and \hsize are 
the dimensions of the document page, a new register \f ullhsize holds the width of 
the two pages combined, and \topmargin and \leftmargin establish the positions 
of the top and left margins of the output page. They are initialized to 

\vsize=6.9in \hsize=4.75in \f ullhsize=10in 
\topmargin= . 75in \lef tmargin= . 5in 

Each page of the document has an empty headline and a footline that contains the 
page number. 

If you find that the default values of these page parameters are not to your 
liking you can simply change them. Such changes should (obviously) appear after 
the \output style command, if there is one. 

Two-sided output 

The previous section described \topinargin ffister whose value determines 

the distance of the text from the top of the page. This was a lie. There are actually two 
registers that handle this task: \oddtopmargin controls the margin on odd-numbered 
pages, and \eventopmargin controls it on even-numbered pages. The \topmargin 
command is just a convenient shorthand for setting both of these registers to the 
same value. By assigning different values to these parameters you can make odd and 
even pages different. 

The above comments also apply to the \lef tmargin command. There are really 
two registers that determine where the left margin of the page is: \oddlef tmargin 
and \evenlef tmargin. It is useful to set these to different values when you want 
to produce two-sided output ("two-sided" meaning that the pages are meant to be 
placed back-to-back) . This way you can arrange it that the text ends up back-to-back 
even when the left and right margins are not the same. Again, \lef tmargin sets both 
registers to the same value. 

You may have guessed by now that the \head and \f oot commands conceal the 
true registers \oddhead, \evenhead, \oddf oot, and \evenf oot. It is very common 
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to set odd and even differently for two-sided output. A book, for example, might 
have a headline that contains the chapter name: 

\oddhead={\hf il Chapter 1} \evenhead={Chapter l\hfil} 

These assignments cause the odd-numbered pages to show the chapter name on the 
right and even numbered pages to show it on the left. 

The \baselinestretch command 

The distance between lines is initialized to an appropriate value when 3yT^ 
starts up, but most technical papers look better if the lines arc moved apart some- 
what to accommodate math symbols in the text. -^yliriX provides the command 
\baselinestretch to accomplish this. A typical example might be: 

\baselinestretch=1200 

The number 1200 is 1000 times the "stretch" apphed to the default hue separation. 
The command above would expand the baseline distance by a factor of 1.2. It will 
also stretch \bigskip, \niedskip, and \smallskip so that they still skip a full line, 
half line, and quarter line, respectively. 

If you make the \baselinestretch very large (a double-spaced document would 
have \baselinestretch=2000, for example), you may find that the positions of the 
headline and footline don't look right. This is because the line separation is now 
bigger than the distance of these lines from the text. This can be fixed by adjusting 
the values of \headskip and \f ootskip. These are normally both set to twice the 
normal line separation (24pt when \typesize=10pt). 

The \baselinestretch can be changed anywhere in the document (but only 
between paragraphs, please). 

Sectioning commands 

%T[5X provides the \chapter, \section, and \subsection commands to facil- 
itate the division of a document into (surprise) chapters, sections, and subsections. 
These all work much the same way. 

Let's start with an example of \chapter. To start a new chapter, all you have 
to do is say 

\chapter{Martian Holiday} 
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(you would probably want to use a different chapter name, but you get the idea). 
That's all there is to it. -^yl^i^ takes care of things like starting a new page, putting 
space above and below, and printing the title left-justified. 

If you choose, ^yi^^ will also keep track of the chapter number and prepend it 
to the title (more on this below). In fact, assuming that you are set up for chapter 
numbers, and that "Martian Holiday" is the third chapter of your tome, the command 
above would yield 

3. Martian Holiday 

It would appear at the top of a fresh page, and subsequent text would start after a 
space of about one and a half lines. 

OK, so it looks rather unimpressive in 12-point roman type. If you want it 
instead to come out big and bold, just type 

{\bigf onts\bf \chapter{Martian Holiday}} 

and that's what you'll get. Notice that you don't write the font-changing commands 
inside the argument to \chapter — that would indeed make the title "Martian Holi- 
day" come out big and bold, but would not change the font of the chapter number. 

UJyT^ encounters a \section or \subsection command the behavior is similar. 
For example, 

\section{Martian Customs} 

first causes a page break if the current page is nearly full (unlike \chapter, which 
always starts a new page). If there is no page break, a little space is skipped, then the 
section title is printed (preceded by a composite of the chapter and section numbers, 
if you so choose), then a little more space is skipped before any following text. The 
same goes for \subsection. 

Of course, you may not like the way -^t/I^iX handles a lot of these details, so here's 
the full story about what goes on behind the scenes (skip this if you don't care). When 
you give a command like \section{Martian Customs} all hell breaks loose. First, the 
macro \sectionbreak decides whether or not to break the page, based on how full it 
is. Next, there is a \vskip by the amount \abovesectionskip. Now the section title 
is actually printed, but how it is output depends on the current \sectionstyle; 
is initialized with \sectionstyle{lef t}, meaning that the section title will appear 
flush left, but you can change this behavior by preceding the \ sect ion command 
by \sectionstyle{center} or \sectionstyle{right}, with obvious consequences. 
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Finally, there is another \vskip by the amount \belowsectionskip. 

If this sounds complicated, just remember that all you have to do is give the 
\section{Martian Customs} command, and the rest (page breaking, putting space 
around the title, justifying) is taken care of for you. The point of mentioning these 
other commands in the "\section family" is that you can change them if you don't 
like what they do. For example, if you want more space after a section name, just 
increase the value of \belowsectionskip (as usual, all of these parameters can be 
found in the Initialization section at the end of jymacros.tex). 



OK, there's more: sectioning (and other) counters 



The rosy picture painted above is a slight oversimplification, because it doesn't 
really explain what happens if you're numbering your chapters, sections, and subsec- 
tions. It is basic %T[t;X philosophy that you should never have to number anything 
"by hand," so internal counters for chapters, sections, and subsections are provided 
to take care of this chore for you. Before getting into how these counters are used in 
the sectioning commands described above, let's first discuss how -^yT^^X manipulates 
numbers. 

Numbers in 3yT^ may be output in any one of a variety of styles. The number 
"16," for example, can be easily and automatically converted into the roman numeral 
"XVI" simply by typing \RomcLn{16}. The full hst of number styles includes: 

\arabic (the usual, e.g., "16") 

\roman (lower case roman numerals, "xvi") 

\Roman (upper case roman numerals, "XVI") 

\alphabetic (lower case letters, "p") 

\Alphabetic (upper case letters, "P") 

\symbols (footnote symbols, see below) 

These styles may be applied to JyT^'s counters as well. For example, the page 
number is stored in a register called \pagenum. If you'd like to print the page number 
in roman numerals, and \pagenum has the value 3, the command \roman\pagenuin 
produces "iii." 

This is all well and good, but the macros that output the page number and other 
counters are already written, so how do you change the output style of these counters 
without delving into the code? No problem: if you want the page numbers to appear 
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as roman numerals, for example, you just put at the beginning of your document 

\pagenumstyle{roman} 

This will change the style of Xpagenum from its default, which is arabic, to roman. 
Note that all -^^^I^^X counters have an associated style command; a quick glance 
at this manual reveals that it was typeset with \chapternumstyle{Roman} and 
\sectionnumstyle{arabic}. 

The \ . . . style commands also accept the argument blank, which suppresses 
the output of the relevant counter. The Xsubsectionnum counter in this manual has 
been blanked out, which is why there are no numbers preceding the slanted subsection 
titles. The default for all of the sectioning counters, in fact, is blank. 

You now know enough to understand the rest of the story on the sectioning com- 
mands. When you give a \chapter command everything proceeds as described above, 
except that when it's time to print the chapter title, if the \chapternumstyle is not 
blank, JyT^ increments Xchapternum, sets all "lesser" counters {i.e., Xsectionnum, 
Xsubsectionnum, and a couple to be named later) to zero, prints the Xchapternum 
as specified by the macro Xchapternumf ormat (another user-modifiable macro which 
just prints the counter in the current style followed by a period), then prints the 
chapter title. If the Xchapternumstyle is blank, Xchapternum is not incremented, 
no counters are set to zero, and the title appears without a chapter number. 

Similarly, if Xsectionnumstyle is not blank, the Xsection command increments 
Xsectionnum, sets lesser counters to zero, prints the Xsectionnum as specified by 
the macro Xsectionnumf ormat (which prints the chapter number if it isn't blank, 
followed by the section number), then prints the section title. No number is printed 
if Xsectionnumstyle is blank. You can figure out how the subsection counter works. 

To end this discussion let me mention a few tricks, which are especially useful if 
you are thinking of playing around with any of the macros. Any counter can be set 
to a desired value via a simple TgX assignment command, e.g., Xchapternum=6. The 
sectioning counters also permit the constructions Xnewchapternum=6 (which sets the 
specified counter) and Xnewchapternum=Xnext (which increments the counter); both 
of these also reset lesser counters to zero. Finally, to print any counter in its current 
style you can simply precede it with Xnumstyle, as in XnumstyleXpagenum. Doing 
things this way makes the printing of the counter sensitive to the value of counter 
style (go back and look at the definition of Xf oot given above for an example.) 
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1.3. Arranging Text 



Now it's time for the macros that help you with actual text. Some of these make 
use of a block structure set up in -^yl^i^, so this is described first. 

Block structure 

It is sometimes desirable to set off part of a file for visual or logical reasons. This 
can be done in an uninteresting and boring way by using comment lines, or in a clever 
and exciting way using \begin{name}. . . \end{name} blocks. To typeset the title 
page of a paper, for example, you could type 

\begin-Ctitlepage} 

(Stuff) 

\end-[titlepage} 

The name given to the block can be anything you want. Blocks may be nested but 
they cannot overlap; in other words, \begin-[a}. . . \begin-[b}-. . . \end{b}. . . \end{a} 
is allowed, but \begin{a}. . . \begin{b}. . . \end{a}. . . \end{b} is not. 

Blocking things in this way has some advantages. The \begin statement opens 
a group that is closed by \end, so parameters can be changed inside the block with- 
out affecting the goings-on outside. For example, if you were to suppress para- 
graph indentation in the case above by giving a \parindent=Opt command after 
\begin{titlepage}, the normal indentation would be automatically restored after 
\end{titlepage}. 

You're probably thinking that this isn't too exciting (braces accomphsh the same 
thing), but there is another feature: when processing \begin{ name}, Jyi^^ executes 
the command \beginname (if it exists) immediately after opening the group. If 
you understand macro definitions this allows you to create blocks with special 
conditions set. Going back to the titlepage example, suppose you want to set 
\pagenumstyle{blank} and \parindent=Opt after \begin{titlepage}. You can 
do this by defining 

\def \begintitlepage{\pagenumstyle{blaiik}\parindent=Opt} 

This is automatically invoked when the titlepage block opens. Similarly, if there 
is an \endtitlepage command defined, it is executed when \end{titlepage} is 
processed, just before closing the group. For this example an appropriate definition 
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might be 

\def \endtitlepage{\newpage}- 
(\newpage does the obvious thing, and is defined below.) In this way you can define 
blocks tailored to your own needs and keep them tucked away in a personal definitions 
file. 

The astute reader will recognize that the \end-C name} command supercedes the 
plain T^]X \end command. Not to worry. 3yF^ has it's own command that does the 
same thing and more, described below. A more serious problem is that T^]X has two 
commands that start with the word begin: \beginsection and \begingroup. If 
you name a block either section or group, ^yF^ will attempt to run these, probably 
with unintended results. 

Line and page breaking: \\ and \newpage 

.7?/TeX provides the \\ command to force a line break 
(like that one, filled at the right with blank space), and the \newpage command to 
force a page break (not demonstrated, but filled at the bottom with blank space). 
No, \\ does not work in math mode. 

Left-justifying, right-justifying, and centering 

The commands \lefttext, \righttext, and \centertext are generalizations 
of T^'s \lef tline, \rightline, and \centerline that allow several lines of text 
to be positioned either 
on the left, 

on the right, 

or in the center. 

They take a single argument, which may be several lines of text separated by \\. For 
example, \righttext {There once was a man\\ from Nantucket,} produces 

There once was a man 
from Nantucket, 

(There should be no \\ after the last fine.) These commands are most useful for short 
applications such as address labels or section headings. 

If you need to justify several paragraphs of text or if you need greater control 
over the output (you may need to add vertical spacing between certain lines, for 
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example), the commands above may fail. The blocks \begin{lef t}. . . \end{left}, 
\begin{right}. . . \end{right}, and \begin{center}. . . \end{center} will handle 
these more difficult cases. Generally you should find that \lefttext, \righttext, 
and \centertext do everything you need, but if some weird problem arises these 
other commands are available. The format is what you expect: 

\begin-[center} 

He said with a grin,\\ 

as he wiped off his chin, 

\end{center} 

produces 

He said with a grin, 
as he wiped off his chin. 

The \beginnarrow. . . \endnarrow block 

T^iX already has a \narrower command that moves the left and right margins 
in by the amount of the usual paragraph indentation. The Jyi^^ version is similar, 
but is constructed with a \begin. . . \end block and can take an optional argument 
[in square braces] specifying the amount the margins are to be moved. 

For example, this paragraph was produced by typing \begin{narrow} 
For example , . . . \end{narrow}. Notice that the margins have moved in by 
an amount equal to an indentation. 

This paragraph also uses \begin{narrow}, but with a 
specified shift of .80 inch. The actual sequence of commands is 
\begin{narrow} [ . 80in] This paragraph. . . \end{narrow}-. 
The amount of the shift can be specified in any units that 
understands and should appear in square braces immediately 
following \begin{narrow}. 

Skipping text 

It may occasionally happen that you'd like to -^yl^ only part of a file (say you're 
working on one section and, to save time, you want to prevent TgX from processing 
the other sections). This is the raison d'etre of the \begin{ignore}. . . \end{ignore} 
block. Absolutely everything sitting between these two commands is skipped over by 
3yi^^ hke it wasn't even there. 
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1.4. Footnotes 



The \f ootnote command 

The \f ootnote command in ^TgX is similar to the one in TgX, so you should 
go read about that one first. The main improvement over TgX is the addition of a 
counter to number the footnotes automatically. This has the nice side-effect that it 
makes the form of the command a little simpler. Just say 

\f ootnote{tea;^ of footnote} 

wherever you want the footnote mark to be* and a footnote appears at the bottom 
of the page. 

The counter \footnotenum is used to generate marks sequentially. Just as the 
\pagenumstyle command determines how the counter \pagenum is output, so the 
\f ootnotenumstyle command determines the appearance of \f ootnotenum. Prob- 
ably the most useful style (the default, in fact) is \f ootnotenumstyle{symbols}-, 
which marks the first footnote with a *, followed by f, I, §, ||, **, ff, ff, §§, and ||||. 

There is a variation of %T[TpC's \f ootnote you can use if you really want to specify 
the footnote mark yourself (like the original T^^X command). If you put 

\f ootnote [marA;] {tea;^ of footnote} 

JyT^ takes whatever appears between the square braces and uses it as the footnote 
mark,^^"° even something as ridiculous as the word "Hello." Use this form if you 
want to imitate T^'s \f ootnote command. 

If for some reason T^ won't let you put a footnote somewhere (like inside an- 
other footnote, for example), it is possible to split up the \f ootnote command into 
two pieces: \f ootnotemark (or \footnotemark [mar/c]), which positions the mark, 
and \f ootnotetext{te3:t of footnote} , which puts the footnote at the bottom of the 
page. The idea is that you put the \f ootnotemark command where the \f ootnote 
command can't go, and put the \f ootnotetext command as soon afterward as pos- 
sible. 

One last little goodie: the spacing between footnotes at the bottom of the page 
can be adjusted by varying the value of \f ootnoteskip. It is initialized to Opt. 



*Sce how easy? 

'°. . . even something as ridiculous as the word "Hello." 
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1.5. Labels 



JyT^iX has a set of macros that allow a character string to be assigned a label, 
which may then be invoked elsewhere as a way to print out the string. If the character 
string is changed by some modification to the document, you need only change the 
definition of the label and all references to the label will substitute the new string. 
This scheme is the basis of the equation and reference numbering routines described 
below. 

Creating and using labels 

Creating a label is easy: just say \la.hel-{.name}-{. character string}. To then print 
out the character string, say \putlab{name}. The label name can include numbers 
and most symbols, but should not contain spaces or commas. As a simple example, 
suppose you are constantly referring to Figure 3 of the document you are JyT^ing, 
but you're afraid that before you're through it might become Figure 4 because of some 
modification, and it would be a pain to have to go through the document changing 
all references to it. Simply make the definition \label{labl}{Figure 3}, and refer 
to the figure by saying, ". . . as we see from \putlab{labl}," which gives ". . . as 
we see from Figure 3." If Figure 3 becomes Figure 4, you need only change the label 
definition (\label{labl}{Figure 4}) instead of the references. (By the way, ^yl^i^ 
will issue the warning 

— > Label name redefined 

if a label is defined more than once, since this could generate problems if done unin- 
tentionally.) 

The sections below describe applications of this facility. 

1.6. Automatic Equation Numbering 

JiJFe^ has a set of commands built out of the labelling macros that will auto- 
matically number equations in a document. They allow you to name and refer to an 
equation via a label, which is translated into a number (automatically generated by 
wherever it appears. You need never type an equation number again. 
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The \eqnlabel and \puteqn commands 

To have ^TfrjX generate an equation number automatically, all you have to do 
is type \eqnlabel-[name} where you would normally put the number. The name is 
the label to which you will refer instead of the number. For example, to get 

strings = everything, (1) 

type 

$$\riii strings = everything, \eqno\eqnlabel{string}-$$ 

The equation number advances each time \eqnlabel is invoked, so if the above 
equation is followed by 

$$\rin physics = chemistry, \eqno\eqnlabel{phys}$$ 

it appears as 

physics = chemistry, (2) 
These equations can now be referred to by invoking their labels instead of their num- 
bers. This is done with a customized version of the \putlab command called \puteqn. 
So to get, "Equations (1) and (2) are silly," type 

Equations (\puteqn{string}) and (\puteqn{phys}) are silly. 

Notice that \puteqn does not put parentheses around the number it returns. This 
is so you can make constructions like ". . . equations (1,2)" by typing ". . . equations 
(\puteqn{string} , \puteqn{phys}) ." 

Generating the equation number 

In general, equation numbers are generated from five counters: the three sec- 
tioning counters (Xchapternum, \sectionnum, and \subsectionnum), a counter for 
the equation itself (Xequationnum), and one more for further numbering just in case 
these aren't enough (\subequationnum). As usual, these two new counters have 
their associated style commands. The equation numbers for string and phys 
above were generated under the assumption that all of these styles were blank except 
\equationnumstyle. This is the default. If none of the counter styles were blank, a 
typical equation might come out like this: 

F = ma (II.l.B.6c) 

Notice that all counters are separated by dots except the last two, Xequationnum and 
\ subequat i onnum. 
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As the compound form of the label suggests, the equation and subequation coun- 
ters are reset whenever the sectioning counters are advanced. This means, for exam- 
ple, that if you have "turned on" the section counter {i.e., made it non-blank), your 
equations will automatically be numbered by section. 

The \eqnlabel command takes care of incrementing the equation number. As 
long as Xsubequationnumstyle is blank, the Xequationnum counter is advanced each 
time \eqnlabel is used, otherwise Xsubequationnum is advanced. This makes it easy 
to produce lettered equations, like 



/ — he, (3a) 

you — he, (3b) 

you = me, (3c) 

we = all together (3d) 

just by saying 

\subequationnumstyle{alphabetic} 

$$\eqalignno{I &= he, & \eqnlabel{walrus-a} \cr 
you &= he, & \eqnlabel{walrus-b} \cr 
you &= me, & \eqnlabel{walrus-c} \cr 
we &= all\; together & \eqnlabel{walrus-d} \cr}$$ 

\ subequat i onnumsty 1 e{bl ank} 

All you have to do is "turn on" the Xsubequationnum counter at the start of the set 
of equations (by setting \subequationnumstyle{alphabetic}-, for example), and 
turn it off at the end (by setting it blank). This last command gets \equationnum 
counting again. 

There is a slightly better way to do the same thing, sort of a shorthand except 
that it doesn't save much typing. The first Xsubequationnumstyle command above 
can be replaced by \begin{eqnseries} and the second by \end{eqnseries}. Inside 
this block the style of Xsubequationnum is set to \eqnseriesstyle, which is initially 
alphabetic but can be changed in the usual way {e.g., \eqnseriesstyle{roman}). 
If that were all there wouldn't be much point, but the eqnseries block has one 
other feature: you may specify an optional label name in square braces immediately 
following the \begin{eqnseries} command, to which will be assigned the equation 
number as it would appear without the attached Xsubequationnum. An example will 
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make this clear. Consider the same equation as above, now using the eqnseries 
block: 

\begin-[eqnseries} [walrus] 

$$\eqalignno{I &= he, & \eqnlabel{walrus-a} \cr 
you &= he, & \eqnlabel{walrus-b} \cr 
you &= me, & \eqnlabel{walrus-c}- \cr 
we &= all\; together & \eqnlabel{walrus-d} \cr}$$ 

\end{eqnseries} 

As in the example without eqnseries, the equation labels walrus-a, walrus-b, 
walrus-c, and walrus-d are assigned numbers hke "3a", "3b", "3c", and "3d." 
But here a label walrus is also generated, and assigned the number "3." This can 
be used in references like "...equations (\puteqn{walrus}b-d), which produces 
". . .equations (3b-d)." 

If you don't like the way the compound equation number looks, you can change it 
to suit your tastes by modifying \puteqnf ormat. This is defined in a fairly straight- 
forward manner in the Initialization section of jymacros .tex. 

\equation, \Equation, and \putequation 

These commands are for those of you that like to put all your equations in a 
separate file, then call them into text when appropriate (by far the best method). 
The command 

\equation{energy}{E=mc~2} 

does two things: first, it assigns the name energy (the first argument) to the equation 
E=mc"2 (the second argument), and second, it appends an equation number generated 
by \eqnlabel (it actually uses the \eqno construction from T^iX). The equation can 
be inserted into the document by using the \put equation command; typing 

$$\putequation{energy}$$ 

produces 

E = mc^ (4) 

The label can be referred to by typing \puteqn{ energy}, as in ". . . the famous 
equation \puteqn{energy}," which gives ". . .the famous equation (4)." Don't be 
confused by the fact that the equation and the label have the same name {Jyi^^ will 
figure out what you mean from context). 
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In the event that you don't want an equation to have an equation number, 
or you want to specify it yourself, or you're using an equation format that doesn't 
permit the use of \eqno (hke \eqalignno), you can't use \equation. For these cases 
^yT^iX supphes the \Equation command instead. \Equation behaves hke \equation 
but doesn't put in an \eqnlabel; you must put one in yourself, if you want one. 
\putequation works the same for equations defined by \equation or \Equation. 

As mentioned above, these commands are useful if you like to put your equations 
in a separate file. There is a disadvantage to this: equations input in this way must 
be stored before use, and if you have too many you could run out of memory. There 
are advantages, however. One is that you can run spelling checkers on the text part of 
your job without getting bogged down by "words" in the equations. Another is that 
you can redefine the \equation and \Equation commands to do operations on just 
the equations. For example, suppose all your equations are in a file called eqns.tex 
and you want to print them out. Just create another file that contains the following 
commands: 

\typesize=12pt 
\draft 

\def\equation#l#2{$$#2\eqno\eqnlabel{#l}$$} 

\def\Equation#l#2{$$#2$$} 

\ input eqns 

\bye 

(The \draft command will be explained later, but what is does here is cause the 
equation labels to appear in the right margin. This makes a handy reference.) 

Figures and tables 

There is currently no provision in -^i/TgX for creating or positioning figures and 
tables, but there are counters in place for you to use if you like. For figures there 
are registers \f igurenum and \subf igurenum with corresponding style commands, 
\f iglabel and \putf ig, a f igseries block, and a \f iglabelf ormat macro. All 
of these work in the same way as their equation counterparts. Similarly, for ta- 
bles you have Xtablenum and \subtablenum and their style commands, \tbllabel 
and \puttbl, a tblseries block, and \tbllabelf ormat. Like Xequationnum and 
Xsubequationnum, the figure and table counters are reset when the sectioning coun- 
ters are incremented. 
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1.7. Automatic Reference Numbering 



Below are a set of commands to handle the numbering of references, which are 
assumed to appear in a list at the end of the document. Like the equation numbering 
routine, you assign a label to each reference instead of a number and Jyi^E^ takes care 
of the rest. Two referencing schemes are supported: in one, references are numbered 
in the order they are cited; in the other, the numbering is determined by the order of 
the final list. In either case, only the references that are actually cited are printed. 

The \ref erencestyle command 

\ref erencestyle (not to be confused with \ref erencenumstyle!) selects one 
of the two reference numbering schemes: sequential, which numbers the references 
in the order they are cited and sees to it that they are output in that order, and 
preordered, which numbers the references in the order they are listed at the end of 
the document. \ref erencestyle{sequential} is the default. 

A little reflection on the dynamics of preordered referencing reveals that it 
requires two passes through the document to implement. You should make sure you 
understand the pitfalls of forward-referenced labels, explained in the Advanced Topics 
chapter, before using this style. 

\ref erence and the \beginputref erences. . . \endputref erences block 

The command \ref erence is used to define a reference and assign to it a label. 
A typical example might be: 

\reference{ref 1}{J. Bloggs, SAT Rev. B21:74 1986} 

The first argument (ref l) is the reference label, the second argument is the reference 
itself. If you want to list more than one paper in a single reference, separate the 
entries by \\: 

\reference-[ref2}{M. Golden, J. Blog. Phys . 106:44 1985\\ 

0. Cheyette, {\it Getting paid to draw pretty pictures 
on my terminal,} to appear in Comm. Time Wast.} 

All \ref erence commands should be listed inside a \begin{putref erences} 
. . . \end{putref erences} block at the place where you want the references to print. 
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For the references above, the end of your document might therefore look hke this: 

{\bf \section{Ref erences}} 
\begin-[putref erences} 

\reference-Cref 1}{J. Bloggs, SAT Rev. B21:74 1986} 
\reference-[ref2}{M. Golden, J. Blog. Phys. 106:44 1985\\ 

0. Cheyette, {\it Getting paid to draw pretty pictures 
on my terminal,} to appear in Comm. Time Wast.} 
\end{putref erences} 

How these references are printed depends on the \ref erencestyle. If you're using 
the sequential style, the references will print in the order they are cited. If you're 
using the preordered style then the order of citing doesn't matter, and the above 
commands will produce 

References 

1. J. Bloggs, SAT Rev. B21:74 1986 

2. M. Golden, J. Blog. Pliys. 106:44 1985 

O. Cheyette, Getting paid to draw pretty pictures on my terminal, to appear in 
Comm. Time Wast. 

There are a couple of things to notice about how the references are formatted. The 
number prefacing each reference is the \ref erencenum, another counter just like all 
the others. It has its associated style command, here set to arable (the default). Its 
appearance in square braces is a consequence of the macro \ref erencenumf ormat, 
which can be found in the Initialization of jymacros.tex and is easily changed 
if it's not to your hking. The "paragraphing" of the reference itself (how \\ is han- 
dled, how lines are indented) is controlled by \putreferencef ormat, also in the 
Initialization section. Space between references can be controlled with T^^X's 
\parskip. 

One final word concerning the output of references: only references that are cited 
somewhere in the document are actually printed. (This means that in the example 
above it has been assumed that both references were cited.) Thus, if your docu- 
ment only needs a handful of references out of a larger database, you can list the 
entire database in the put references block (or better yet, call it in with an \ input 
command). The extraneous \reference's will not appear in the output. 
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Citing a reference with \putref 

Citing a reference should be like referring to an equation — you should specify the 
reference label which is then turned into a number by JyT^^. This is the job tackled 
by \putref , the referencing scheme's variant of \putlab. 

In the simplest case, \putref allows you to refer to the work of Dr. Bloggs 
above by saying "...thus the result of reference [\putref {ref 1}] must be 
wrong," and have it come out ". . . thus the result of reference [1] must be wrong." 
But it is frequently desirable to cite several sources at once, so \putref takes multiple 
arguments. For example, if the references yin and yang are assigned the numbers 6 
and 9, the command \put ref {yin, yang} produces "6,9". Furthermore, if \putref 
is given three or more arguments, it looks for sequences and outputs them appro- 
priately. Specifically, if larry, moe, and curly correspond to references 1, 2, and 3, 
the command \putref {larry, moe, curly} yields "1-3", not "1,2,3". As you would 
expect, \putref puts out numbers in the form demanded by \ref erencenumstyle 
(here arable) — it does not look at \ref erencenumf ormat, which only affects the 
appearance of the reference number in the final reference list. 

If you're the kind that likes to make citations raised and in smaller type like 
this^^l (that's an example, not a footnote), you can use the \markup command in 
conjunction with a \putref . \markup takes whatever follows and puts it up, so that 
last example could have been done ". . . like this\markup{ [\putref {ref 1}] }." 

1.8. Remaining Bits 

Underlining and overlining 

This is a fast one. In Tf^^X the commands \underline and \overline work only 
in math mode. In -^yT^^X they work in normal text as well. 

The \draf t command 

This is a very good command to put in your file if you're not printing out 
the final copy of the document. In \draf t mode, the word "DRAFT" appears in the 
headline along with the date and time, overfull boxes are marked with a black bar, 
and the names assigned to the equations and references (if you're using the automatic 
numbering routines) are written in the margin next to the things they label. This 
makes it easy to look up the names when you want to refer to these items. 
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\draf t mode also shifts the text over to accommodate notes in the right margin. Are 

you 

You just have to say \marginnote{s^?xj9^} somewhere in the text of a paragraph (it's following 
not allowed between paragraphs) and the stuff will migrate out to the margin and 
appear in very small print. Jyi^^ is not very sophisticated in how it handles this, so if 
your notes are very long or very frequent you may get weird output. A \marginnote 
command is ignored unless you're in \draf t mode. (The one above was doctored to 
make it come out anyway.) 

Xdraft's monkeying with the margins makes for a couple of restrictions. First, 
you can't use it with \outputstyle{twoup}, because the margins aren't big enough. 
Second, since \draft needs to have the last word on margin settings, it should be 
one of the last commands to appear before the start of the text. 

Signing off: saying goodXbye 

The correct way to end a JyF^ file is with the command \bye. This is a shght 
change from which allows both \end and \bye. As mentioned above, \end has 
been superceded. (If you really need the version of \end, you can get it with 
\TeXend.) 
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II. ADVANCED TOPICS 



II. 1. Label Tricks 

Forward-referencing 

The label routines are so sophisticated that they actually allow you to refer to a 
label before it's been defined. The basic idea is this: during the first pass through a 
document the values of all such forward-referenced labels are stored in a file, which is 
then automatically read in during subsequent passes to supply the label values. The 
user doesn't have to do anything differently, but some care must be taken as there 
are all kinds of warnings and errors that can be generated. 

Here are the details. When -^yl^ sees a \putlab for a label that has yet to be 
defined, it immediately prints the warning 

— > Label name referenced before its definition 

If it hasn't occurred already, %T[t;X also opens a file in which to save the as-yet- 
undefined label; the name of this file is the same as the file being JyF^ed, but with 
the extension . lab. When this happens, you will see the message 

— > Creating file file. lab 

The values of the needed labels are then written to this file as they are defined. If 
any are missing {i.e., if you forget to define a label you use), you get the warning 

— > Label name referenced but never defined 

Once you succeed in running without generating this error, you will have a . lab file 
that contains all the values of all the forward-referenced labels. 

Now comes the fun part. When you run the file again, the first thing -^yl^^X does 
is to go get the . lab file: 

— > Getting labels from file file. lab 

You should not see any warning messages about forward-referencing, because the 
label values are supplied from the . lab file. However, if you've changed any labels 

between the first run and the second, you may get the warning 

— > Definition of label name doesn't match value in file. lab 

This is telling you that the label value pulled from the . lab file and the value assigned 
by the subsequent Mabel command don't match. The solution is to ^yT^ the file 
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yet again, until you get no more warnings. You can then be sure that all forward- 
referenced labels are supplied with the correct character strings. 

Any label that is likely to be forward-referenced should be fairly short. This is 
because the label will have to be written to a file, and regardless of its length T^jX will 
output it as a single line. On some systems a line of more than a couple of hundred 
characters creates problems. 

commands in labels 

You may wonder whether you can put Tf^X commands in a label instead of a 
character string. The answer is yes (in fact the reference numbering routine does this), 
but it's tricky. The \label macro creates an expanded definition, so any commands 
appearing in the label string will be expanded until can't expand anymore. If 
you want to play around with this, check out the section of the T^iXbook on expanded 
definitions (Chapter 20). 

II.2. Job Streams 

The best way to typeset a long document (at least in the draft stage) is to break 
it up into sections that can be T^iXed separately. A problem with this approach, 
however, is that a label reference in one section to material in an earlier section will 
be unrecognized. For example, suppose you're typesetting a book chapter-by-chapter, 
and you're using the automatic equation numbering routine described above. If in 
chapter two you try to refer to an equation in chapter one you will get a complaint 
from 3yF^ that the equation label is not defined. The problem is simply that the 
labels defined in the first chapter are not available to the second unless the two 
chapters are typeset together. This problem can be overcome by job streaming. The 
trick is to have chapter one produce a file containing label information that chapter 
two can input for reference. 

The \streamto and \streainf rom commands 

If you give the command Nstreamto at the beginning of a job, it causes all labels 
(including all automatically generated equation numbers and references) and allJyT^ 
counter values to be dumped into a file. The name of the file is either generated from 
the name of the job {jobname. str for the straight Nstreamto command), or can 
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be specified by giving an optional argument in square braces (Nstreamto [filename] 
creates a file filename . str) . ^yT^ always supplies the extension . str. 

This file can be retrieved by another job by giving a \streamf rom command. 
The format is the same as Nstreamto: Nstreamf rom looks for a file jobname . str, 
\streamf rom [/iZename] looks for filename .str. In this way all of the labels and 
counter values are made available to the new job. 

For example, suppose chapter one of your book is in the file chapl.tex and 
chapter two is in chap2 . tex, and you want to make the labels and counter values of 
chapter one available to chapter two. Simply put the command \streamto [chap2] at 
the beginning of chapl.tex and \streamfrom at the beginning of chap2.tex. Now 
when you ^yT^ chapl . tex the stream file chap2 . str is created, and when you -^^/Tf^X 
chap2.tex this file is automatically input by the \streamf rom command. As long as 
the stream file is around, chapter two will be able to refer to all the labels in chapter 
one without generating errors. Of course, it is up to you to see that the stream file 
has up-to-date information; in other words, if you make changes to chapter one, you 
should re-JyT^ it to create a new stream file for chapter two. 

If there is a chap3 .tex and you want to make available to it the labels of chapter 
two, you can put a \streamto [chap3] command in chap2.tex. If this command 
is given before the \streamf rom then the contents of chap2 . str will be copied to 
chap3 . str, so that chapter three will also be able to refer to the labels of chapter 
one. Using this technique you can arrange it so that later chapters always have all of 
the labels of previous chapters available to them. 

Writing to a stream Gle 

To send information of your own out to the stream file just write to \streamout 
using T[t;X's \immediate\write command. If you introduce a special counter, for 
example, the command 

\immediate\write\streamout{\mycounter=\the\mycounter} 

will write it's current value to the stream file. Obviously, you should make sure 
you understand T^^X's \write command before attempting this. The conditional 
\if streaming is available to test whether or not the stream file has been opened. 
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II.3. Rolling Your Own 



Getting extra fonts 

There may come a time when the fonts provided by ^TgX just aren't enough, 
and you want to use the T^^X \f ont command to go and get some of your own. Herein 
Ues a problem. The amount of space available for extra fonts is limited because ^TgX 
fills up virtually all of its memory with the various sizes and styles described earlier. 
Nevertheless, there is room for a few additional fonts. 

If you need more than a few new fonts you have a couple of alternatives. One 
is to not specify a \typesize. This may seem pretty radical, but in fact -^yl^ has 
been designed to behave very much like plain TJ^X if the \typesize command is not 
given: the base size is lOpt, fonts are available in 7pt and 5pt for subscripts and 
sub-subscripts, and some size-changing commands are disabled. There is also a little 
more room for extra fonts, maybe ten or twenty depending on their size. 

If you want to input even more fonts you have to get basic and use plain T^. 
This can be tricky and tedious. You may find the file jyfonts.tex helpful. 

Dates and times 

The current date and time is made available to T^rpC each time a job is run. 
gives you access to this information through the following commands: 

\year (current year) 

\month (number of the current month) 

\day (current day of the month) 

\time (current time in minutes since midnight) 

JyT^ also provides 

\shortyear (the last two digits of the current year) 

\standardhour (current hour in 12-hour format) 

\militaryhour (current hour in 24-hour format) 

\amorpm (either "am" or "pm") 

All of these are token registers, so their values are retrieved using the command \the, 
e.g., \the\year, \the\amorpm. Additionally, there are the commands \monthword 
and \monthabbr, which take a single numerical argument and return the name of the 
corresponding month (full name and three letter abbreviation, respectively). 
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Prom these pieces you should be able to format dates and times in the usual 
ways. 3yr^ provides a few of the more common formats: \today (the full month 
name, day, and year), \standardtime (current hour and minute in 12-hour format), 
and Xmilitarytime (current hour and minute in 24-hour format). Retrieving these 
values does not require using \the. 

A couple of hacks: \everyoutput and \everybye 

T^]X has registers that allow you to insert your own tokens or commands whenever 
you enter certain modes. For example, you can use the register \everypar to put 
something at the beginning of every paragraph. Continuing in this tradition, 3yT^ 
adds the registers \everyoutput (for tokens to insert whenever %T[t;X starts to output 
a page) and \everybye (for tokens to insert whenever JyT^ ends a job). 

The job of \everybye is to finish off the final page, and as a consequence it is 
not initially empty, in contrast to other \every . . . commands. Its default value is 

\everybye={\par\vf il} 

which closes the final paragraph and adds some infinite glue to fill the page. This is 
a very useful register if you want to modify the closing routine, say to accommodate 
a special format. 
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